home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / hash.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  5.8 KB  |  186 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  Internet Systems Consortium, Inc. ("ISC")
  3.  * Copyright (C) 2003  Internet Software Consortium.
  4.  *
  5.  * Permission to use, copy, modify, and distribute this software for any
  6.  * purpose with or without fee is hereby granted, provided that the above
  7.  * copyright notice and this permission notice appear in all copies.
  8.  *
  9.  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10.  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11.  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12.  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13.  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14.  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15.  * PERFORMANCE OF THIS SOFTWARE.
  16.  */
  17.  
  18. /* $Id: hash.h,v 1.4.18.2 2005/04/29 00:16:55 marka Exp $ */
  19.  
  20. #ifndef ISC_HASH_H
  21. #define ISC_HASH_H 1
  22.  
  23. /*****
  24.  ***** Module Info
  25.  *****/
  26.  
  27. /*! \file
  28.  *
  29.  * \brief The hash API
  30.  *    provides an unpredictable hash value for variable length data.
  31.  *    A hash object contains a random vector (which is hidden from clients
  32.  *    of this API) to make the actual hash value unpredictable.
  33.  *
  34.  *    The algorithm used in the API guarantees the probability of hash
  35.  *    collision; in the current implementation, as long as the values stored
  36.  *    in the random vector are unpredictable, the probability of hash
  37.  *    collision between arbitrary two different values is at most 1/2^16.
  38.  *
  39.  *    Altough the API is generic about the hash keys, it mainly expects
  40.  *    DNS names (and sometimes IPv4/v6 addresses) as inputs.  It has an
  41.  *    upper limit of the input length, and may run slow to calculate the
  42.  *    hash values for large inputs.
  43.  *
  44.  *    This API is designed to be general so that it can provide multiple
  45.  *    different hash contexts that have different random vectors.  However,
  46.  *    it should be typical to have a single context for an entire system.
  47.  *    To support such cases, the API also provides a single-context mode.
  48.  *
  49.  * \li MP:
  50.  *    The hash object is almost read-only.  Once the internal random vector
  51.  *    is initialized, no write operation will occur, and there will be no
  52.  *    need to lock the object to calculate actual hash values.
  53.  *
  54.  * \li Reliability:
  55.  *    In some cases this module uses low-level data copy to initialize the
  56.  *    random vector.  Errors in this part are likely to crash the server or
  57.  *    corrupt memory.
  58.  *
  59.  * \li Resources:
  60.  *    A buffer, used as a random vector for calculating hash values.
  61.  *
  62.  * \li Security:
  63.  *    This module intends to provide unpredictable hash values in
  64.  *    adversarial environments in order to avoid denial of service attacks
  65.  *    to hash buckets.
  66.  *    Its unpredictability relies on the quality of entropy to build the
  67.  *    random vector.
  68.  *
  69.  * \li Standards:
  70.  *    None.
  71.  */
  72.  
  73. /***
  74.  *** Imports
  75.  ***/
  76.  
  77. #include <isc/types.h>
  78.  
  79. /***
  80.  *** Functions
  81.  ***/
  82. ISC_LANG_BEGINDECLS
  83.  
  84. isc_result_t
  85. isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, unsigned int limit,
  86.            isc_hash_t **hctx);
  87. isc_result_t
  88. isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit);
  89. /*!<
  90.  * \brief Create a new hash object.
  91.  *
  92.  * isc_hash_ctxcreate() creates a different object.
  93.  *
  94.  * isc_hash_create() creates a module-internal object to support the
  95.  * single-context mode.  It should be called only once.
  96.  *
  97.  * 'entropy' must be NULL or a valid entropy object.  If 'entropy' is NULL,
  98.  * pseudo random values will be used to build the random vector, which may
  99.  * weaken security.
  100.  *
  101.  * 'limit' specifies the maximum number of hash keys.  If it is too large,
  102.  * these functions may fail.
  103.  */
  104.  
  105. void
  106. isc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp);
  107. /*!<
  108.  * \brief Attach to a hash object.
  109.  *
  110.  * This function is only necessary for the multiple-context mode.
  111.  */
  112.  
  113. void
  114. isc_hash_ctxdetach(isc_hash_t **hctxp);
  115. /*!<
  116.  * \brief Detach from a hash object.
  117.  *
  118.  * This function  is for the multiple-context mode, and takes a valid
  119.  * hash object as an argument.
  120.  */
  121.  
  122. void
  123. isc_hash_destroy(void);
  124. /*!<
  125.  * \brief This function is for the single-context mode, and is expected to be used
  126.  * as a counterpart of isc_hash_create().
  127.  *
  128.  * A valid module-internal hash object must have been created, and this
  129.  * function should be called only once.
  130.  */
  131.  
  132. /*@{*/
  133. void
  134. isc_hash_ctxinit(isc_hash_t *hctx);
  135. void
  136. isc_hash_init(void);
  137. /*!<
  138.  * \brief Initialize a hash object.  
  139.  *
  140.  * It fills in the random vector with a proper
  141.  * source of entropy, which is typically from the entropy object specified
  142.  * at the creation.  Thus, it is desirable to call these functions after
  143.  * initializing the entropy object with some good entropy sources.
  144.  *
  145.  * These functions should be called before the first hash calculation.
  146.  *
  147.  * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash
  148.  * object as an argument.
  149.  *
  150.  * isc_hash_init() is for the single-context mode.  A valid module-internal
  151.  * hash object must have been created, and this function should be called only
  152.  * once.
  153.  */
  154. /*@}*/
  155.  
  156. /*@{*/
  157. unsigned int
  158. isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key,
  159.          unsigned int keylen, isc_boolean_t case_sensitive);
  160. unsigned int
  161. isc_hash_calc(const unsigned char *key, unsigned int keylen,
  162.           isc_boolean_t case_sensitive);
  163. /*!<
  164.  * \brief Calculate a hash value.
  165.  *
  166.  * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash
  167.  * object as an argument.
  168.  *
  169.  * isc_hash_init() is for the single-context mode.  A valid module-internal
  170.  * hash object must have been created.
  171.  *
  172.  * 'key' is the hash key, which is a variable length buffer.
  173.  *
  174.  * 'keylen' specifies the key length, which must not be larger than the limit
  175.  * specified for the corresponding hash object.
  176.  *
  177.  * 'case_sensitive' specifies whether the hash key should be treated as
  178.  * case_sensitive values.  It should typically be ISC_FALSE if the hash key
  179.  * is a DNS name.
  180.  */
  181. /*@}*/
  182.  
  183. ISC_LANG_ENDDECLS
  184.  
  185. #endif /* ISC_HASH_H */
  186.